Create a Document and Signature Definitions Resource

Alias

DocumentCreation

Description

Creates a document and signature definitions resource. This resource can be created for two purposes: generating multiple signatures on a document or signing several external data objects from their hashes or several XMLDSig/XAdES Manifest objects.

In the first case, currently, only resources of this type containing a document and a definition of the PAdES-Basic, PAdES-BES, and PAdES-EPES, XMLDSig, XAdES-BES or XAdES-EPES signatures can be created.

Important

Subsequently, more signature definitions can be added via the Create a signature definition operation. If a document and signature definitions resource contains several signature definitions, the signatures for these definitions must be performed sequentially, i.e., without interweaving the operations for obtaining the hash of the document with operations for inserting the digital signature corresponding to different signature definitions.

In the second case, currently, only resources of this type containing an empty document and a definition of the externally detached XMLDSig/XAdES signature can be created.

The operation is useful for:

  • Signing a batch of documents: for uploading the documents (and optionally the signature definitions) for subsequently creating the corresponding signature process.

  • Signing a document and delegating the orchestrating of the signature process to the TRIDENT: for uploading the document (and optionally the signature definitions) for subsequently creating the corresponding signature process.

  • Signing a document and orchestrating the signature process.

Request

POST /trustedx-resources/esignsp/v2/documents

Authorization

The request must contain a bearer access token generated by an authorization server of the platform. This token must have a scope that includes the urn:safelayer:eidas:sign:process:document value and must be used as explained in RFC 6750. Basically, the access token must be included in an Authorization header as follows:

Authorization: Bearer <token>

The client application must obtain the required access token via client credentials grant OAuth 2.0 interaction with the platform.

Content-Type Header

There are three possibilities, depending on whether the resource is created for (i) signing a document provided with the signature definitions, (ii) signing a document provided without the signature definitions or (iii) signing multiple external data objects from their hashes.

If the resource is created for signing a document provided along with the signature definitions:

Content-Type: multipart/form-data; boundary=<part_boundary_mark>

Where <part_boundary_mark> is the string that delimits the parts of the multipart entity inserted in the body.

If the resource is created for signing a document provided without the signature definitions:

In this case, the Content-Type corresponds to the type of document to be signed (e.g., application/pdf, text/xml, etc.)

The resource is created for signing multiple external data objects from their hashes or several XMLDSig/XAdES Manifest objects:

Content-Type: application/json

Body

There are three possibilities, depending on whether the resource is created for signing a document provided with the signature definitions, signing a document provided without the signature definitions, or signing several external data objects from their hashes or several XMLDSig/XAdES Manifest objects.

The resource is created for signing a document provided along with the signature definitions

Contains a multipart/form-data entity with two parts: one of them, "signers", is optional and contains a JSON array with the data required for creating the signature definitions of the resource. If no signature data is provided (i.e., the "signers" part contains an empty array), this data must be provided subsequently to the resource via the create a signature definition operation. The other part, "document", contains the document to be assigned to the resource (subsequently, the document to be signed). The Content-Type header of this part specifies the type of this document (a PDF if the value in the header is application/PDF, an XML document if the value is text/xml;charset="UTF-8", etc.). The Content-Transfer-Encoding header of the "document" part is only necessary when the document to be signed is encoded in binary (a PDF document, a PNG image, etc).

------x1Xxx2XXxxx3XXX3xxxXX2xxX1x
Content-Disposition: form-data; name="signers"
Content-Type: application/json
 
[
{
"signature_policy_id" : {string},
"parameters" : {Parameters}
}
]
------x1Xxx2XXxxx3XXX3xxxXX2xxX1x
Content-Disposition: form-data; name="document";
Content-Type: application/pdf
Content-Transfer-Encoding: binary
 
<doc>
------x1Xxx2XXxxx3XXX3xxxXX2xxX1x--

The resource is created for signing a document provided without signature definitions

In this case, the body contains the document to be signed.

The resource is created for signing multiple external data objects from their hashes or several XMLDSig/XAdES Manifest objects

In this case, the body contains a JSON object with the data required for creating the signature process:

[
{
"signature_policy_id" : {string},
"parameters" : {Parameters}
}
]

Properties of the JSON object containing the data for creating the signature definitions

The JSON object containing the data used for creating the signature definitions has the following properties:

Property

Usage

Description

signature_policy_id

Required

Value assigned to the signature_policy_id property of one of the signature definitions of the resource created. If the resource is created for signing a document provided, the property can have the following values:

  • "urn:safelayer:eidas:policies:sign:document:pdf": definition of an ETSI PAdES signature (ETSI TS 102 778).

  • "urn:safelayer:eidas:policies:sign:document:xml": definition of a W3C XMLDSig/XAdES signature (ETSI TS 101 903).

If the resource is created for signing multiple external data objects from their hashes, the property can only have the value "urn:safelayer:eidas:policies:sign:document:xml".

parameters

Optional

Value assigned to the parameters property of one of the signature definitions of the resource created. This property is optional and can be omitted in some array elements.

Response

Status-Line

If the document and signature definitions resource is created successfully, the HTTP response will contain the following Status-Line (see HTTP Response Status for all the possible cases).

HTTP/1.1 201 Created

Location Header

URL of the document and signature definitions resource created. This URL has the following structure:

Location: https://<host>:<port>/trustedx-resources/esignsp/v2/documents/{doc_and_sigdefs_id}

Where {doc_and_sigdefs_id} is the identifier of the document and signature definitions resource created.

Content-Type Header

Content-Type: application/json

Body

Contains a JSON object with the following structure:

{
"id" : {string},
"self" : {string},
"signers" : [
{
"id" : {string},
"self" : {string}
}
]
}

Property

Description

id

Identifier of the document and signature definitions resource.

self

URL of the document and signature definitions resource created.

signers[]

Information on the signature definitions contained in the resource created.

signers[].id

Identifier of one of the signature definitions contained in the resource created.

signers[].self

URL of one of the signature definitions contained in the resource created.

Example

HTTP/1.1 201 Created
Location: http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_111
Content-Type: application/json
 
{
id" : "idd_111",
self" : "http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_111",
"signers" : [
{
"id" : "ids_222",
"self" : "http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_111/signers/ids_222"
}
]
}